Core Print Objects(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 2 - Core Printing Features / About Core Printing Features

Core Print Objects
QuickDraw GX printing information is contained in a set of print objects that you associate with a printable document. When you create a job object, QuickDraw GX sets up references to a format object and paper-type object. The initial values for the properties in each of these objects is defined by the printer driver for the default output printer.
The following sections describe specific properties of the job object, the format object, and the paper-type object.

Job Object Properties
A job object has ten accessible properties, as shown in Figure 2-2. Note that, because the data structure of a job object is private, the order of the properties as shown in Figure 2-2 is completely arbitrary. Properties in italics indicate references to other objects.
Figure 2-2 The job object

The properties of a job object are as follows:

Output printer. A reference to the output printer to which documents are sent for printing. A user specifies an output printer in the Print dialog box. The initial value contained in this property is the default output printer, which is the printer to which documents are sent if the user does not select a different printer.
Formatting printer. A reference to the printer for which documents are formatted. A user specifies a formatting printer in the Page Setup dialog box. The initial value contained in this property is the default formatting printer, which is used to format documents if the user does not specify a different printer.
Reference constant. This property contains a reference constant for your application's use. In the reference constant you can associate your own data with a particular job object. For example, you may wish to store a pointer to the document data. Specifying a reference constant for a job object is discussed in the chapter "Advanced Printing Features" in this book.
Error. This property specifies the most recent error encountered for a particular job object. QuickDraw GX associates printing-related errors with individual job objects. It is necessary for you to check for errors after calling certain functions. Job object errors are discussed in "Error Handling" beginning on page 2-14.
Format mode. This property specifies the mode associated with a particular job object. QuickDraw GX supports text, PostScript, and graphics direct modes. By default, your application uses the graphics direct mode to print text and graphics. Direct modes allow your application to take advantage of a printer's built-in features, such as fonts and text-streaming capabilities, to provide faster output for users. Using direct mode, however, does not take full advantage of QuickDraw GX features; therefore, the appearance of the document may change when printed in direct mode. The user can specify a direct mode in the Print dialog box. Direct modes are discussed in the chapter "Advanced Printing Features" in this book.
Format list. A list of references to format objects. The first reference is to format object that represents the default format. The default format is defined by the printer driver of the default output printer. The user can change the value of the default format in the Page Setup dialog box. Using multiple format objects in a document is discussed in the chapter "Page Formatting and Dialog Box Customization" in this book. Format object properties are discussed in the next section.
Paper-type list. A list of references to the paper-type objects that are associated with the job's format objects. The user can change the default paper type in the Page Setup dialog box. Using different paper-type objects in a document is discussed in the chapter "Advanced Printing Features" in this book.
Page range. This property contains the user-specified page range. A user specifies a page range in the Print dialog box. How you determine the page range is discussed in "Printing Documents Using QuickDraw GX" beginning on page 2-20.
Panel dimensions. This property defines the dimensions of QuickDraw GX dialog box panels. You use this information when you want to locate the position of the cursor within a panel. Panel dimensions are discussed in the chapter "Page Formatting and Dialog Box Customization" in this book.
Collection. A reference to a job collection object, which stores additional information about the print job. The job collection object is discussed in the chapter "Page Formatting and Dialog Box Customization" in this book.

Format Object Properties
A format object contains six accessible properties, as shown in Figure 2-3. Note that, because the data structure of a format object is private, the order of the properties as shown in Figure 2-3 is completely arbitrary. Properties in italics indicate references to other objects.
Figure 2-3 The format object

The properties of a format object are as follows:

Dimensions. This property defines the physical dimensions of the paper (the paper size) and the printable area within these dimensions (the page size) after scaling and orientation have been applied. Scaling is the percentage that objects are shrunk or grown when printed. The orientation is either portrait or landscape.
Mapping. This property defines the mathematical representation of the format object's settings, such as scaling. The mapping property of a format object is discussed in the chapter "Page Formatting and Dialog Box Customization" in this book.
Form. This property defines a backdrop that can be applied to a set of pages. A form is made up of two shape objects--a shape that defines the form and another shape that defines a mask, which represents the erasable area within the form. Forms are discussed in the chapter "Page Formatting and Dialog Box Customization" in this book.
Paper type. A reference to a paper-type object associated with this format object. Paper-type object properties are discussed in the next section.
Collection. A reference to a format collection. Through this reference, you can access additional information related to the format collection. This information includes data such as the user-specified orientation (either portrait, landscape, or rotated landscape) from the Page Setup dialog box. The format collection is discussed in the chapter "Page Formatting and Dialog Box Customization" in this book.
Job. A reference to a job object. Through this reference, you can access the job object associated with a particular format object.

Paper-Type Object Properties
A paper-type object contains four accessible properties, as show in Figure 2-4. Note that, because the data structure of a paper-type object is private, the order of the properties as shown in Figure 2-4 is completely arbitrary. Properties in italics indicate references to other objects.
Figure 2-4 The paper-type object

The properties of a paper-type object are as follows:

Name. This property contains the name of a paper type, such as US Letter. A user specifies a paper-type name in the Page Setup or Custom Page Setup dialog box. Paper-type object names are discussed in the chapter "Advanced Printing Features" in this book.
Dimensions. This property defines the physical dimensions of the paper (the paper size) and the printable area within these dimensions (the page size) before scaling and orientation have been applied. Paper-type object dimensions are discussed in the chapter "Advanced Printing Features" in this book.
Collection. A reference to a paper-type collection. Through this reference, you can access additional information related to the paper-type object. This information includes such data as paper-type units. The paper-type collection is discussed in the chapter "Page Formatting and Dialog Box Customization" in this book.
Job. A reference to a job object. Through this reference, you can access the job object associated with a particular paper-type object.